(SST) ShlWAPI.pas Version 1.08
Developer Reference
(SST)ShlWAPI StrStrNW Function
Searches the specified number of characters in a string for an exact match of another string.
Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).
Syntax
function StrStrNW(lpFirst : LPCWSTR; lpSrch : LPCWSTR; cchMax : UINT) : LPCWSTR;  
Parameters
lpFirst [in] Pointer to, or address of, the null-terminated, Unicode string in which to search.
lpSrch [in] Pointer to, or address of, the null-terminated, Unicode (sub-)string to find/locate.
cchMax [in] The maximum number of characters (counted from the beginning of the string being searched) in which to search for an occurrence of the string specified in the lpSrch parameter.
Return Values
If the function succeeds in locating the substring within the specified number of characters of the string being searched, it returns a pointer to the beginning of the substring within the searched string. If the function fails for any reason, it returns NIL.
Remarks
Unlike StrStrNIW, which ignores character case during the search, StrStrNW performs a case sensitive search. The results of a search may therefore differ significantly, even if both functions are called with the same parameters, as is demonstrated by the example below and on the page describing StrStrNIW.
This function is only exported in a Unicode and not, like most other ShlWAPI.dll functions, in both an ANSI and a Unicode version.
Although the function is exported by name as of ShlWAPI.dll version 6.0 under Windows 2000 and, possibly, earlier Windows versions with IE 6.0, it is erroneously documented as being exported by Shell32.dll and requiring Windows Vista. Furthermore, the first declaration of the function prototype in ShlWAPI.h is enclosed in a compiler directive that uses an undeclared constant ("_WIN32_IE_IE6").
To import and call the function when using the SST implementation of the ShlWAPI.pas unit, it is necessary to specify "SST_SHLWAPIVER6PT0", either in the source code or in the project settings. In the example below, the required compiler directive was specified in the first line of the source code.
Example
{$DEFINE SST_SHLWAPIVER6PT0} {$IFDEF SST_SHLWAPIVER6PT0} PROCEDURE TForm4.TestShlWAPIStrStrNW(Sender : TObject); VAR strtosrchfor : WideString; VAR txttosearch : WideString; VAR uptocharnum : UINT; VAR apiretptr : POINTER; VAR newinfoline : STRING; BEGIN strtosrchfor := ''; txttosearch := ''; uptocharnum := 0; apiretptr := NIL; newinfoline := ''; strtosrchfor := 'FoX'; //Compare to the first parameter of the first example in the StrStr sample code uptocharnum := 16; txttosearch := 'The quick, brown fox jumped over the fence and hid in the fox burrow'; newinfoline := 'StrStrNW called with lpFirst (without the quotation marks) = "' + txttosearch + '", lpSrch = ' + strtosrchfor + ', and cchMax = ' + IntToStr(uptocharnum); Memo1.Lines.Add(newinfoline); apiretptr := StrStrNW(PWChar(txttosearch), PWChar(strtosrchfor), uptocharnum); IF apiretptr <> NIL THEN newinfoline := 'StrStrNW returned a pointer to "' + PWChar(apiretptr) + '"' ELSE newinfoline := 'StrStrNW returned NIL !'; Memo1.Lines.Add(newinfoline); strtosrchfor := 'FENCE'; uptocharnum := 42; txttosearch := 'The quick, brown fox jumped over the fence and hid in the fox burrow'; newinfoline := 'StrStrNW called with lpFirst (without the quotation marks) = "' + txttosearch + '", lpSrch = ' + strtosrchfor + ', and cchMax = ' + IntToStr(uptocharnum); Memo1.Lines.Add(newinfoline); apiretptr := StrStrNW(PWChar(txttosearch), PWChar(strtosrchfor), uptocharnum); IF apiretptr <> NIL THEN newinfoline := 'StrStrNW returned a pointer to "' + PWChar(apiretptr) + '"' ELSE newinfoline := 'StrStrNW returned NIL !'; Memo1.Lines.Add(newinfoline); strtosrchfor := ' fence'; //Blank as text to search for uptocharnum := 42; txttosearch := 'The quick, brown fox jumped over the fence and hid in the fox burrow'; newinfoline := 'StrStrNW called with lpFirst (without the quotation marks) = "' + txttosearch + '", lpSrch = ' + strtosrchfor + ', and cchMax = ' + IntToStr(uptocharnum); Memo1.Lines.Add(newinfoline); apiretptr := StrStrNW(PWChar(txttosearch), PWChar(strtosrchfor), uptocharnum); IF apiretptr <> NIL THEN newinfoline := 'StrStrNW returned a pointer to "' + PWChar(apiretptr) + '"' ELSE newinfoline := 'StrStrNW returned NIL !'; Memo1.Lines.Add(newinfoline); txttosearch := 'The quick, brown fox jumped over the fence and hid in the fox burrow'; strtosrchfor := 'fox'; uptocharnum := Length(txttosearch); // = is the length of the string being searched newinfoline := 'StrStrNW called with lpFirst (without the quotation marks) = "' + txttosearch + '", lpSrch = ' + strtosrchfor + ', and cchMax = ' + IntToStr(uptocharnum); Memo1.Lines.Add(newinfoline); apiretptr := StrStrNW(PWChar(txttosearch), PWChar(strtosrchfor), uptocharnum); IF apiretptr <> NIL THEN newinfoline := 'StrStrNW returned a pointer to "' + PWChar(apiretptr) + '"' ELSE newinfoline := 'StrStrNW returned NIL !'; Memo1.Lines.Add(newinfoline); txttosearch := 'The quick, brown fox jumped over the fence and hid in the fox burrow'; strtosrchfor := 'T'; uptocharnum := 1; newinfoline := 'StrStrNW called with lpFirst (without the quotation marks) = "' + txttosearch + '", lpSrch = ' + strtosrchfor + ', and cchMax = ' + IntToStr(uptocharnum); Memo1.Lines.Add(newinfoline); apiretptr := StrStrNW(PWChar(txttosearch), PWChar(strtosrchfor), uptocharnum); IF apiretptr <> NIL THEN newinfoline := 'StrStrNW returned a pointer to "' + PWChar(apiretptr) + '"' ELSE newinfoline := 'StrStrNW returned NIL !'; Memo1.Lines.Add(newinfoline); txttosearch := 'The quick, brown fox jumped over the fence and hid in the fox burrow'; strtosrchfor := 'T'; uptocharnum := 0; newinfoline := 'StrStrNW called with lpFirst (without the quotation marks) = "' + txttosearch + '", lpSrch = ' + strtosrchfor + ', and cchMax = ' + IntToStr(uptocharnum); Memo1.Lines.Add(newinfoline); apiretptr := StrStrNW(PWChar(txttosearch), PWChar(strtosrchfor), uptocharnum); IF apiretptr <> NIL THEN newinfoline := 'StrStrNW returned a pointer to "' + PWChar(apiretptr) + '"' ELSE newinfoline := 'StrStrNW returned NIL !'; Memo1.Lines.Add(newinfoline); Memo1.Lines.Add(''); END; {$ENDIF}
The above example code produces the following output:
StrStrNW called with lpFirst (without the quotation marks) = "The quick, brown fox jumped over the fence and hid in the fox burrow", lpSrch = FoX, and cchMax = 16 StrStrNW returned NIL ! StrStrNW called with lpFirst (without the quotation marks) = "The quick, brown fox jumped over the fence and hid in the fox burrow", lpSrch = FENCE, and cchMax = 42 StrStrNW returned NIL ! StrStrNW called with lpFirst (without the quotation marks) = "The quick, brown fox jumped over the fence and hid in the fox burrow", lpSrch = fence, and cchMax = 42 StrStrNW returned a pointer to " fence and hid in the fox burrow" StrStrNW called with lpFirst (without the quotation marks) = "The quick, brown fox jumped over the fence and hid in the fox burrow", lpSrch = fox, and cchMax = 68 StrStrNW returned a pointer to "fox jumped over the fence and hid in the fox burrow" StrStrNW called with lpFirst (without the quotation marks) = "The quick, brown fox jumped over the fence and hid in the fox burrow", lpSrch = T, and cchMax = 1 StrStrNW returned a pointer to "The quick, brown fox jumped over the fence and hid in the fox burrow" StrStrNW called with lpFirst (without the quotation marks) = "The quick, brown fox jumped over the fence and hid in the fox burrow", lpSrch = T, and cchMax = 0 StrStrNW returned NIL !
Requirements
Unit: Declared and imported in (SST)ShlWAPI.pas
Library: (SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode: Implemented as Unicode (StrStrNW) function only.
Min. ShlWAPI.dll version according to MS SDK doc.: undocumented
Min. ShlWAPI.dll version based on SST research: 6.0
Min. OS version(s) according to Microsoft SDK doc.: Windows Vista
Min. OS version(s) according to SST research.: Windows 2000 with IE 6
See Also
StrStrNIW, StrStrI, StrStr, StrCSpn, StrCSpnI.
 
Windows APIs: StrStrNW, StrStrNIW, StrStrI, StrStr, StrCSpn, StrCSpnI.


Document/Contents version 1.00
Page/URI last updated on 07.12.2023 		 
Copyright © Stoelzel Software Technologie (SST) 2010 - 2015 		Suggestions and comments mail to:
webmaster@stoelzelsoftwaretech.com